Skip to content

Add macOS support and customizable prompt messages#53

Merged
chamodanethra merged 12 commits intomainfrom
feature/platform-support-macOS
Dec 9, 2025
Merged

Add macOS support and customizable prompt messages#53
chamodanethra merged 12 commits intomainfrom
feature/platform-support-macOS

Conversation

@chamodanethra
Copy link
Owner

Summary

This pull request introduces macOS support for biometric authentication and enhances the flexibility of the prompt displayed during key creation.

Features

  • macOS Support:

    • Adds biometric-protected key generation, signing, and decryption using the Secure Enclave for macOS 10.15+.
    • Implements platform-specific configurations (MacosConfig) and integrates with Touch ID.
    • Isolates Keychain items by prefixing identifiers with the app bundle ID to prevent conflicts.
    • Supports RSA-2048 and EC P-256 signing, as well as hybrid decryption modes.
  • Customizable Prompt Messages:

    • Adds an optional promptMessage parameter for key creation, allowing developers to customize the text shown during biometric authentication.
    • Ensures backward compatibility with a default message: "Authenticate to create keys."

Documentation & Examples

  • Updates README.md with platform integration steps for macOS and notes on the new promptMessage parameter.
  • Adds macOS support to passwordless_login, document_signer, and banking_app examples, including all necessary macOS project files, CocoaPods integration, and entitlements.

Other Changes

  • Refactors macOS-related methods for improved key deletion logic.
  • Includes a version bump to 8.5.0.

This commit introduces support for macOS, enabling biometric-protected key generation, signing, and decryption using the Secure Enclave.

### Features
- **macOS Configuration**: Adds `MacosConfig` to specify key creation options, including signature algorithm (`RSA` or `ECDSA`) and credential type.
- **Platform Integration**: The core `createKeys`, `sign`, and `decrypt` methods now accept macOS-specific configurations (`MacosConfig`, `MacosSignatureOptions`, `MacosDecryptionOptions`).
- **Native Implementation**: Integrates with the native macOS platform channel to perform cryptographic operations.
- **Documentation**: Updates documentation to reflect macOS support, including supported algorithms and hybrid modes.

### Example App
- The example application is updated to handle key creation and decryption on macOS, treating it similarly to iOS (`isApplePlatform`).
This commit adds macOS support to the `banking_app` example application.

### Changes
- Adds the necessary macOS project files, including `Runner.xcodeproj`, configurations (`.xcconfig`), `Info.plist`, entitlements, and workspace settings.
- Includes a `Podfile` for managing macOS dependencies.
- Configures the Xcode project with build schemes, build phases, and required capabilities like Keychain access and Secure Enclave usage.
- Adds standard Swift files for the application delegate (`AppDelegate.swift`) and main window (`MainFlutterWindow.swift`).
This commit adds macOS support to the `document_signer` example application. A complete macOS project structure, including Xcode configurations, entitlements, and source files, has been created.

The main `example` app's macOS project was also updated to remove a hardcoded development team.
This commit introduces macOS support for the `document_signer` and `passwordless_login` example applications. It also removes the default widget test from the `document_signer` app.

### Changes
- **macOS Support**: Adds the necessary macOS project files, configurations (`.xcconfig`, `Podfile`, entitlements), and dependencies to enable the `document_signer` and `passwordless_login` example apps to build and run on macOS.
- **Default Test Removal**: Deletes the boilerplate `widget_test.dart` from the `document_signer` example.
- **Project Updates**: Updates Xcode project settings and dependencies for both example apps to align with macOS requirements, including adding CocoaPods support.
…login

This commit enables macOS support for the `passwordless_login` example application by integrating CocoaPods and configuring necessary entitlements.

### Changes
- **Entitlements**: Adds entitlements for both `Debug` and `Release` builds to enable access to the Keychain, Secure Enclave, and user-selected files.
- **CocoaPods Integration**:
    - Adds `Podfile.lock` and integrates CocoaPods into the Xcode project.
    - Updates the Xcode workspace (`.xcworkspace`) and project file (`.pbxproj`) to include Pods dependencies, frameworks, and build phases.
- **Build Phases**: Introduces new shell script build phases for checking the Pods manifest lock and embedding Pods frameworks.
Simplifies the `SecItemDelete` call for the encrypted RSA key by reusing the `encryptedKeyAttributes` dictionary.
Prefixes keychain identifiers with the application's bundle identifier (`Bundle.main.bundleIdentifier`).

This change prevents potential keychain item conflicts when multiple applications on the same macOS system use this plugin. The affected identifiers are `biometricKeyAlias`, `ecKeyAlias`, `invalidationSettingKey`, and the domain state service. A default prefix is used if the bundle ID is unavailable.
This commit introduces full support for biometric authentication on macOS using Touch ID, enabling signing and decryption capabilities consistent with the existing iOS and Android implementations.

### Features
- **macOS Platform Support**: Adds native support for macOS 10.15+ using the Security framework and Touch ID.
- **New Configuration**: Introduces `MacosConfig` to manage platform-specific settings like `useDeviceCredentials` and `signatureType` (RSA/ECDSA).
- **Keychain Isolation**: Keychain identifiers are now prefixed with the app's bundle identifier on macOS to prevent conflicts between different applications using the plugin.
- **Signing and Decryption**:
    - Implements hardware-backed RSA-2048 and EC P-256 signing.
    - Supports ECIES and RSA decryption, including hybrid modes.
- **Biometric Enrollment Binding**: Keys can be bound to the current Touch ID enrollment, automatically invalidating them if biometrics change.

### Documentation
- Updates `README.md` with instructions for macOS integration, including required entitlements and `Podfile` configuration.
- Adds `MacosConfig` to the API documentation.
- Updates the platform support table to include macOS 10.15+.
This commit introduces a new optional `promptMessage` parameter to the `createKeys()` method.

When `enforceBiometric` is set to `true`, this parameter allows developers to customize the text displayed in the biometric authentication prompt. If not provided, it defaults to "Authenticate to create keys" to ensure backward compatibility.

This feature enables providing more context-specific instructions to users during the key generation process on Android, iOS, and macOS. The `README.md` and `CHANGELOG.md` have been updated to reflect this change.

This also includes a version bump to `8.5.0` and updates to placeholder metadata in the macOS podspec.
Adds an optional `promptMessage` parameter to the mock `createKey` method in `biometric_signature_test.dart`. This enhances test flexibility by allowing the prompt message to be specified during key creation tests.
@chamodanethra chamodanethra merged commit 6b6d490 into main Dec 9, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant